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Chapter 2: Template files 


The TRS process uses action and screen templates to maneuver through the 
screens of a host application. These templates provide the host with the same 
input as a terminal operator. These templates also receive the output from the 
host. 


This chapter explains how to 


e determine the actions a terminal operator performs to enter and retrieve 
information 


e create the action and initial action template files that define the sequence 
of host application screens for each transaction 


e create the screen template files that define the sequence of fields 
encountered on each screen 


Note: If you make backups of your template files, do not store them in the 
/a/ivr/3270 directory, or in any subdirectory under /3270. You should make a 
directory at the same hierarchical level or higher as /3270 (for example, 
/a/ivr/3270bak). TRS searches the /3270 directory and any subdirectories 
within it for files with the .act or .scn extensions. 


Determining the required transactions 


Imagine that you are an operator sitting at a terminal. In order to perform a 
specific task, you type information and press function keys until you 
accomplish the desired task. Perhaps a caller asks you to look up a customer’ s 
account balance, or enter an order. The series of steps you perform at the 
terminal enable the application on the host computer to complete the 
transaction. 
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To develop a voice application that accesses the same information as a 
terminal operator, you need to tell Meridian IVR 2.0/I how to execute the 
same series of actions that the terminal operator executes. You provide this 
information in ASCII files called screen and action template files. 


Screen and Action template files provide the layout and content of each 
screen in the host application as the terminal operator sees them. Figure 2-1 
compares a transaction done by a terminal operator to one done by a customer 
calling into a voice response system. 


Note: The first step performed by the terminal operator is not performed by 
the action template. It is performed by the initial-action template (described 
later in this chapter). The initial-action template handles the login and moves 
the application to the appropriate screen to begin the transaction. 


TRS requires two types of template files: 


e Action templates, which describe the sequence of screens traversed in 
order to perform a specific transaction. Figure 2-4 shows an example of 
an action template. 


555-9001-318 Standard 1.0 February 1996 


Template files 2-3 


Figure 2-1 
Terminal operator vs. voice response system 














An operator follows this A customer follows this sequence 


sequence to retrieve data: 


1. Starts the “accounting” 
application. 


2. Selects the “Accounts 
Receivable” menu option. 


3. Asks the caller for account 
information. 


4. Enters the callers account 
number. 


5. Reports the balance when 
the customer's information 
appears on the screen. 


to retrieve data: 


1. Calls into the IVR application, 
activating a voice application. 


2. When prompted, selects the 
Accounts Receivable option from a 
menu prompt. 


3. Whenprompted, enters account 
information. At this point, the appli- 
cation sends a request for informa- 
tion to TRS. TRS then executes the 
action template for this specific 
transaction. 


4. Hears the playback of 
requested information. 





5. Hangs up. 


e Screen templates, which validate each screen, define the fields on the 
screen that require data, and define all keystrokes required for the screen. 


Figure 2-2 shows how screen templates relate to action templates. 
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Figure 2-2 
Action and screen templates 


#action-template 
action-type 
screent 

screen2 

screens 


#screen1-template 
screent 
field-descriptor1 
field-descriptor2 
key-descriptor 


#screen2-template 
screen2 
field-descriptor1 
field-descriptor2 
key-descriptor 


#screen3-template 
screens 
field-descriptor1 
field-descriptor2 
key-descriptor 





5250-based applications often have format inconsistencies that make it 
difficult for TRS to efficiently determine when the host application is ready 
for input and what region of the host screen contains vital information. These 
inconsistencies are due to the character based nature of the 5250 protocol. 


In addition, the 5250 communication protocol has no way of notifying TRS 
that host data transmission has ended. From the terminal operator’ s 
perspective, it is easy to tell when host transmission ends because the 
operator’s requested information appears on the screen. From TRS’s 
perspective, there is nothing inherent in the 5250 protocol to provide 
notification of the end of host output. The TRS encounters a stream of data 
from the host, and from this must determine the identity of each screen as well 
as locate the end of each screen. To enable TRS to do this, as well as cope 
with screen inconsistencies, you must create a file called screen.conf. 
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The action templates, screen templates, and screen.conf file are ASCII text 
files that use a simple syntax to define the screen flow and input/output fields. 
The sections that follow provide a detailed explanation of the templates, as 
well as the information necessary to create the screen.conf file. 


Action templates 


A 5250 transaction typically moves through several screens until it locates 
specific information. The screens may be a series of commands issued at the 
operating system prompt, or they may be screens within an application 
running on the host computer. Whenever Meridian IVR 2.0/I references an 
action template, the 5250 Gateway executes the screen templates listed in the 
action template, moving through the application just as a terminal operator 
would. An action template must specify the same sequence of screens that the 
terminal operator traverses. 


A separate action template defines each transaction. In the example shown in 
Figure 2-1, if you want to select a menu option other than “Accounts 
Receivable,” you would define another action template. 


Action templates describe the flow of the screens that comprise a particular 
transaction. For example, if you want a transaction to access billing 
information for a specific client, as a terminal operator you would perform the 
following steps: 


Procedure 2-1 
Accessing billing information 


1 Log in to the computer. 

2 Start the “acct” application. 

3 Select the “Accounts Receivable” menu. 

4 When prompted, enter the client’s account number and press <Enter>. 


A screen appears displaying the client’s billing information. 
5 Read the account information on the screen. 


In an Meridian IVR 2.0/1 5250 transaction, an initial-action template 
performs steps 1 and 2. The TRS automatically executes the initial-action 
template at TRS startup (initial-action templates are described later in this 
chapter.). An action template created to execute this transaction would 
perform steps 3 through 5. 
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Action template syntax 


Figure 2-3 
Action template syntax 


An action template is an ASCII file created with a text editor. The action 
template files you create must reside in the /u/ivr/3270 directory or in a 
subdirectory below /u/ivr/3270, and must have the file name extension .act. 
For example, if you created an action template called getbalance.act, it would 
have this path: 


/u/ivr/3270/getbalance.act 


The syntax of an action template is shown in Figure 2-3. 





The lines depicted as ¢ are additional screen templates used in the transaction. 
Each screen template corresponds to a specific host application screen, and is 
listed in the action template in the same order as encountered during an actual 
terminal session. (Screen templates are discussed later in this chapter.) The 
example in Figure 2-4 illustrates an action template file which describes a 
transaction for retrieving account information. 
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Figure 2-4 
Action template example 





In Figure 2-4, action-name is getbalance, the name of the action template file 
without the .act extension. The app-name is accounting. The reset-action is 
reset_cust (file name reset_cust.act), and the logout-action is logout_cust (file 
name logout_cust.act). Manual mode is omitted because manual mode is not 
required for this transaction (a description of manual mode follows). 


The remaining lines identify the sequence of screens (acctrec, acctno, and 
customer) TRS must traverse to retrieve the customer billing information. 
These screens are listed in the order that they must be accessed. 


An explanation of each entry in the action template syntax follows. 


#comment 

The first line of the template in Figure 2-3 is a comment. The comment line 
is not required, but is recommended to describe the purpose of the action 
template. It is good practice to heavily comment files so that you or others can 
easily make changes to the templates in the future. 


Comments lines start with the “#” symbol and can be embedded anywhere in 
the action template. A comment takes the entire line; no non-comment fields 
may precede or follow the comment in that line. 
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action-name 

The action-name is the file name of the action template file without the .act 
extension. The action-name is required to begin the transaction. For example, 
if the action template’s file name is getbalance.act, you would enter 
getbalance for the action-name. 


app-name 


When you install the 5250 Gateway on your application processor, you must 
create a trs.conf file that assigns TRS session numbers to the application on 
the host computer (the trs.conf file is described in Chapter 3). Choose a name 
for the host computer application name; it does not need to match any actual 
application name on the host computer. 


As an example, this guide uses the app-name “accounting” to represent the 
host computer “acct” application. 


The app-name you specify in the action template must exist in the trs.conf file 
(discussed in Chapter 3). Meridian IVR 2.0/I passes the app-name to TRS 
function, which uses the name to start the appropriate session with the host 
computer. 


reset-action 

The reset-action specifies an action template to be processed when the 
transaction completes or if the transaction fails. Typically, the reset-action 
template is used to bring the host computer application back to its main screen 
so it is ready to process the same type of transaction. Figure 2-5 shows the 
sequence a sample reset-action template follows. 
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Figure 2-5 
Reset-action template sequence sample 
For an action template The reset-action template 
that follow this sequence: follows this sequence: 
Main Main 
Menu Menu 
Screen Screen 
Billing Billing 
Application Application 
Screen Screen 
Customer Customer 
Information Information 
Screen Screen 




















Entering a hyphen in the reset-action entry indicates that no reset-action 
template is specified. 


If no reset-action template is specified and the transaction being executed by 
the action template fails, the logout-action template (described in the next 
section) is executed. If the transaction succeeds and there is no reset-action 
template specified, the host computer application remains at the screen where 
the transaction ended. 


When you create a reset-action template, do not specify reset-action or 
logout-action templates in it. For example, Figure 2-6 shows a sample 
reset-action template. 
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Figure 2-6 
Reset-action template sample 





The action template using this reset-action template would enter reset_cust as 
the reset-action entry. 


logout-action 

The logout-action specifies a logout-action template to be executed if the 
reset-action template fails, or if the transaction fails and there is no 
reset-action template specified. If the transaction succeeds, the logout-action 
template is not executed. 


The TRS uses the logout-action template to return the failed transaction to the 
initial screen (usually a login screen). After it successfully executes the 
logout-action template, it executes the initial-action template (described later 
in this chapter) after 30 seconds. Figure 2-7 shows the flow of the logout 
action template. 
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Figure 2-7 
Logout action flow 


For an initial-action template that brings the host computer Logout-action Template 
application to the accounting package menu, and an action 
template that brings the host computer application from the 
Application Menu Screen to the Customer Information 
Screen, then the logout-action template brings the host 
computer application back to the Login Screen. 


Action Template t 
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The logout-action template locates the screen where the transaction failed. If 
for example, the transaction failed at the account number screen, the 
logout-action template locates the screen template with the appropriate 
validation tag and starts from that screen. 


Entering a hyphen “-” for the logout-action entry indicates that no 
logout-action template is specified. If neither a reset-action template nor a 
logout-action template is specified and the transaction fails, the host 
computer application remains at the point where the transaction failed. Future 
transactions that try to use this session would also experience errors because 
the screen where the session remained would not be the expected starting 
screen (unless the transaction can start from any screen). 


When you create a logout-action template, do not specify reset-action or 
logout-action templates. Figure 2-8 shows a sample logout-action template. 
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Figure 2-8 
Logout-action template sample 





screen-template 

The screen-template (the file name of the template without the .scn extension) 
identifies the screen template used during the 5250 transaction. Enter the 
screen templates in the exact order they appear during the transaction. Each 
screen template must be listed on a separate line. The syntax for screen 
templates is described later in this chapter. 


<manual mode> (optional field) 

The <manual-mode> entry allows you to attach a session resource to a 
particular channel. You can then use the same session for consecutive 
Meridian IVR 2.0/I transactions. This type of session is not released when the 
transaction is finished. To exit manual mode you must execute a COMA cell 
in the Meridian IVR 2.0/I application or process another action template that 
does not contain the manual mode option. Chapter 4 describes how to use the 
COMA cell. 


To specify manual mode, enter manual after the logout-action template name. 
If you omit manual, automatic mode is used for the template. In automatic 
mode, the session assigned to the action template is free for use when the 
transaction is completed. 
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Note: You should not specify a reset-action template in an action template 
that uses manual mode. Manual mode is designed to stay at a specific screen. 
The next transaction received by the session will start at the last screen of the 
action template that used manual mode. This next transaction should use 
automatic mode and specify a reset-action template that brings the session 
back to the starting screen of the first action template (that specified manual 
mode). 


Screen templates 


Screens used by the host computer could be a series of commands entered at 
the system prompt coupled with the system’s response to those commands, or 
screens defined by applications on the host computer. You should define 
screen templates that issue the system commands to start the application 
(usually as part of the initial-action template), and then screen templates that 
make menu selections and enter or retrieve data from the screens displayed 
by the application. This guide uses an accounting application as an example. 


Each screen contains fields. For the 5250 Gateway, a field is any place on the 
screen where data is entered or displayed. For example, the cursor location 
after a system prompt where you would type a command is considered a field. 
Also, within an application, the area on the screen where an account balance 
is displayed is also considered a field (the traditional definition of a field). 


For a specific transaction, specific data is entered in certain fields, and data is 
read from other fields. A screen template identifies those fields on the screen 
that are used to process a transaction. Only the fields that are used in the 
transaction are included in the template. Figure 2-9 shows a sample screen. 
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Figure 2-9 
Fields and the system prompt 





The entry shown for the screen in Figure 2-9 has not yet had the <Enter> key 
pressed. If <Enter> was pressed the application would have been started and 
the screen replaced by the application screen. In Figure 2-9, “vad” has been 
entered into the login field. A sample application screen showing fields is 


shown in Figure 2-10. 
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Figure 2-10 
Fields in a host computer application 





In Figure 2-10, “Jane K. Smith” is entered in a field. 


Different transactions may access different fields on a screen. For example, 
a transaction to locate the payment due would only need to access that field, 
while a transaction retrieving the customer’s balance would only need to 
access the Current Balance field. 


A screen template is an ASCII file created with a text editor. The screen 
template files you create must reside in or under the Meridian IVR 2.0/1 
/a/ivr/3270 directory, and must have the file name extension .scn. For 
example, if you created a screen template called customer.scn, it would have 
this path: 


/u/ivr/3270/customer.scn 


For each accessed field, there should be a field descriptor specified that 
governs how data is retrieved from or entered in the field. The screen 
template can include both data input entries as well as data output entries. 


Screen template syntax 


The syntax of a screen template is shown in Figure 2-11. 
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Figure 2-11 
Screen template syntax 





The lines depicted as * are additional field-descriptor lines. The example in 
Figure 2-12 illustrates a screen template file that obtains the balance from the 
screen shown in Figure 2-10. 


555-9001-318 Standard 1.0 February 1996 


Template files 2-17 


Figure 2-12 
Screen template example 





In Figure 2-12, the first line is a comment describing the screen template file. 
The screen-name is “customer,” the name of the screen template file without 
the .scn extension. The “1,1” represents the location of the validation tag on 
the screen. The row is listed first, followed by the column. “Account” is the 
screen validation tag. 


The fourth line is the field-descriptor that describes an action to take. This 
field descriptor is going to find an exact match to “Balance:” and place the 
contents of the field into a buffer. The field-descriptor line has many 
variations, depending on what you want to do with a field. For example, the 
fourth line in Figure 2-12 could be entered as: 


2,48—$ 


This would place the contents of the field starting at 2,48 into the next buffer. 
See “field-I/O” later in this section. 


An explanation of each entry in the screen template follows. 
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#comment 


The first line of the template in Figure 2-12 is a comment. The comment line 
is not required, but is recommended to describe the purpose of the action 
template. It is good practice to heavily comment files so that you or others can 
easily make changes to the templates in the future. 


Comments lines start with the “#” symbol and can be embedded anywhere in 
the action template. A comment takes the entire line. No non-comment fields 
may precede or follow the comment in that line. 


screen-name 


The first non-comment line specifies the name of the screen. This is the 
screen template file name without the .scn extension. 


validation-tag offset 


This entry specifies the position of the validation-tag by row and column. 
You may enter 0,0 for the validation-tag offset in only two cases: 


e To indicate that you do not want to validate this screen (you would also 
need to enter a hyphen, “—”, as the validation-tag). You should only 
ignore the identity of a screen if you want TRS process to perform the 
actions specified in the screen template regardless of what screen is 
actually active. For example, if you want to execute a command at the 
system prompt, you would not need to verify that you are at a specific 
screen, as long as you are sure the screen has a system prompt. 


Note: In general, you should validate screens whenever possible. 
This ensures data for the host computer application is sent to the 
correct screen, and data sent back to the Meridian IVR 2.0/1 
application is from the correct screen. 


e To tell TRS to search the screen for the validation tag. If you do not 
know the exact location of the validation tag or if the location of the 
validation varies, you can tell TRS to search the screen for the tag. Enter 
0,0 for the offset, then enter the validation tag in the appropriate field. 


validation-tag 


This entry specifies the validation-tag used on the screen. The entry should 
be text that always appears in the same location every time this screen 
displays. For the example, “Account” is always displayed starting at location 
1,1 whenever a customer’s Account Receivable screen is displayed. 
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At the end of the previous screen template, you may want to use a clear screen 
function (or execute the ENTER key 24 times using key-descriptor lines ) so 
you know the starting point for information on the screen, especially if the 
screens you are accessing on the host computer scroll. For example, if you 
execute an application and it starts displaying information at the current 
cursor location, you need to know the current cursor location to be able to 
validate that screen. 


Enter a hyphen, “-”, for the validation-tag to indicate that you do not want to 
validate this screen (you would also need to enter 0,0 as the validation-tag 
offset). As described previously, you should only use this method of 
validation if you want TRS process to perform the action specified in the 
template regardless of what screen is actually active. 


Note: If the screen you need to validate is a blank screen, enter this line for 
the items: screen-name, validation-tag offset, and validation-tag: 


blank 1,1. BLANKSCREEN 


The word “blank” is a placeholder; the 1,1 and BLANKSCREEN are 
required. 


field-descriptor 

This line identifies the location and name of a field on the screen, and the 
action to be performed. You can enter as many field-descriptor lines as 
necessary to perform the task needed on the screen. The field-descriptor lines 
should be entered in the same order as they are accessed for the transaction. 
Figure 2-13 shows the syntax for field-descriptor lines. 
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Figure 2-13 
Field-descriptor syntax 





Note: If the application running on the host is stream-based, meaning the 
screen scrolls as the user enters data and retrieves responses, you should enter 
the field-descriptor as follows: 


0,0 - BLANKOUT 


In this instance, the field-descriptor will clear TRS memory space associated 
with the application screen so that your application call flow will know where 
to retrieve the appropriate data. 


row,column 

If TRS is going to read information from a field on the host screen, this entry 
locates the field on the screen. If you know the exact location of the field TRS 
is reading from, you can enter it in row, column format. If you do not know 
the exact location of the field TRS is reading from, or if the location of the 
field varies, you can enter 0,0 and TRS will search for a match to the name 
specified in field name. For unformatted, character-based applications, you 
must specify the exact location. 
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In 5250 transactions, writing to the terminal screen always occurs at the 
current cursor position. Therefore, if the field I/O action is writing text to the 
host screen, TRS will write the text to the screen at the current cursor position 
regardless of the row,column you specify. 


If you enter “0,0” and a hyphen for the row,column and field-name entries, 
the field I/O specified is executed at the current cursor location. 


To locate field-names on the screen for reading, the offset of the upper left 
corner of the screen is 1,1 and the lower right corner is 24,80. 


field-name 

This entry identifies the field being accessed on the terminal screen. If the 
field-descriptor is 0,0 (that is, for an exact match), the field-name must 
uniquely match text on the screen or must be a hyphen to indicate that the 
field is at the current cursor position. When entering the field name, keep in 
mind that TRS process right-justifies all field names and removes all extra 
white space. If the transaction fails, this field identifies the current screen so 
the reset-action template can be executed. 


If you enter “0,0” and a hyphen for the row,column and field-name entries, 
the field I/O specified is executed at the current cursor location. 


To specify a location on the screen that does not have an associated 
field-name, use a hyphen, “-”, for the field-name entry. If you do, you must 
specify a location, such as 24,8 for the location of the action specified by the 
field-I/O entry. 


field-I/O 


This entry indicates the action to be taken on the field. Table 2-1 explains the 
valid entries for this field. 
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Table 2-1 
Valid field I/O entries 


Inputs the contents of the next input buffer (transmitted from 


the Meridian IVR 2.0/I application) into the field. 


Outputs the contents of the field into the next output buffer. 
num is a number in the range 1—31 and represents the 
number of characters in the field TRS will put in the output 
buffer. If you do not assign num a value, TRS will place 31 
characters into the buffer. 


%n$ Outputs the contents of the field into an internal variable 
named n, which must be a number from 1-9 


%n* Enters the contents of internal variable n into the field. 


%n$num Outputs the first num characters of the field into variable n. 


Any text string to be entered in the field. If any of the special 
characters listed in this table are to entered as text, enclose 
the entire text in quotes (e.g., “$abc”). 


BLANKOUT | Clears TRS memory space associated with the host 
application screen before retrieving output. 


Note: Place the asterisk and dollar sign characters in quotation marks if your 
field-descriptors require their use without their associated buffer commands. 





For retrieving data into an output buffer, $num indicates the number of 
characters to be retrieved from the field; using $ without a number retrieves 
characters until an attribute is encountered, or a maximum of 31 characters 
have been retrieved. 


Internal variables (indicated by the % symbol) are used within the 5250 
screens only and cannot be transmitted through the TRS gateway. You can 
only use internal variables to store and enter data from one screen to another 
in the host computer application. To send the data to the Meridian IVR 2.0/I 
application that called TRS process, you need to store the data in an output 
buffer. 
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When entering a field-descriptor, the entries on the line should be separated 
by white space or tab characters. If you are entering text for the field I/O, TRS 
ignores any white space you include with the value until it encounters the new 
line character (e.g., the value includes several words). 


Note: The order of the field-descriptor lines in your screen template file 
determines how data is entered and retrieved from the screens and written into 
the input and output buffers of aCOMO cell. Chapter 4 describes how to use 
Meridian IVR 2.0/I cells to retrieve data from the host computer. 


key-descriptor 

Identifies a key to be used with the screen. To send information to the 
computer for processing or to execute a command, the terminal operator 
presses a key on the terminal keyboard. If you do not specify a key, nothing 
is sent to the host and the current screen does not change. The key could be 
the ENTER key or a function key. The format of this line is similar to the 
field-descriptor. Figure 2-14 contains the format of the key-descriptor. 


Figure 2-14 
Format of key-descriptor line 





position-indicator 
This entry should be set to 0,0. 


Meridian IVR 5250 Gateway Development Guide Product release 2.0/1 


2-24 Template files 


> 


This character indicates that this line contains a key. 


keyname 


The name of the key for this screen. Table 2-2 lists the valid keys you can 
enter. 


Table 2-2 
Valid key names 


This line may appear anywhere after the screen-name line (that is, the first 
non-comment line). As with field-descriptor lines, the entries on this line 
must be separated by white space or tab characters. 
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sleep-descriptor (optional) 

A sleep-descriptor causes the transaction to pause for a specified number of 
seconds. You can use a sleep-descriptor to pause the transaction for a 
specified period of time before or after processing a key-descriptor. The 
waiting period takes into account the time the host computer may take to 
process the information entered on the screen, and to move to the next screen. 
The transaction waits at any point where you place a sleep-descriptor. 


Usually, a sleep-descriptor is placed after a key-descriptor to indicate that the 
session should wait for a specified amount of time to ensure that the next 
screen is ready. 


Each sleep-descriptor follows the syntax shown in Figure 2-15. 


Figure 2-15 
Sleep descriptor format 





position-indicator 
This entry should be set to 0,0. 


@ 


Identifies that this line is a sleep-descriptor. 
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num 


Specifies the number of seconds that the session should sleep. For example, 
to wait 25 seconds, you would code the sleep-descriptor as 


0,0 @25 


Initial-action templates 


Before you can process any information on the host computer using the 5250 
Gateway, you need to set the starting point for each of your terminal sessions. 
For example, you may want session 2 to start processing at an application’s 
main menu, whereas session 5 should start at the system prompt. 


You should automatically initialize each terminal session by defining 
initial-action templates. Initial-action templates are action templates that 
specify a sequence of screen templates that position the terminal session at the 
desired location on the host computer whenever TRS is started up. 


The initial-action template follows the same format and syntax as defined for 
action templates earlier in this chapter. If you must use “*” or “$” characters 
in your field-descriptors, put them in quotation marks. 


Instead of referencing these action templates in the COMI cell, you specify 
initial-action templates in an ASCII file named trs.conf. See Chapter 3 for 
information on the configuration and syntax of the trs.conf. 
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